Overview

This page provides instructions for taking an "out-of-the-box" Raspberry Pi and making it "project-ready" by downloading and configuring the operating system to enable features which are most likely to be used by hobbyists. For example, auto-login and auto-launching of python scripts will be enabled, so that projects will auto-start when power is applied. I should provide the disclaimer, that these are the steps that I use, and some of the selections may be different for you. For example, timezone, keyboard layout, etc.

Hardware Tested

These instructions were tested on a Raspberry Pi 3 Model B, and a Raspberry Pi 2 Model B. The Raspberry Pi 3 Model B is a 1.2 GHz 64-bit quad-core ARM Cortex-A53 processor with integrated 802.11n WiFi and integrated Bluetooth 4.1. The Raspberry Pi 2 Model B is a 900 MHz 32-bit quad-core ARM Cortex-A7 that does not include integrated wireless. For convenience, an Edimax or similar Wi-Fi USB adapter can be used with the RPi 2. Alternatively, both versions include a 10/100 Mbit/s wired Ethernet connection.

Raspberry Pi 3 Model B

Raspberry Pi 2 Model B	+	(optional) Edimax Wi-Fi USB Adapter or similar

Raspberry Pi 1 Model B+	+	(optional) Edimax Wi-Fi USB Adapter or similar

Downloading the Linux image

Before configuring the Raspberry Pi, it is necessary to download the Linux operating system, and install it on the Raspberry Pi. In order to accomplish this step you will need the following:

• A Linux operating system image for the Raspberry Pi
• A micro-SD card with at least 8GB
• A micro-SD card writer
• A program to write the image to the SD card

NOTE: regarding the micro-SD card size, I would recommend using the smallest card possible. After you have done all of this hard work, you are going to want to save your image. If you use a 32 GB card, your image will be 32 GB. Additionally, I have had compatibility issues, where an image made on one brand of 8 GB SD card, will not fit on an 8 GB SD card from a different vendor. This means that whatever image size you save, you could be forced to save it to an SD card one size larger (assuming your cards are all inconsistent like mine).

Normally, I would recommend downloading the latest Raspbian image here: http://www.raspberrypi.org/downloads/raspbian, however, with the rapid pace of hardware and software changes on the Raspberry Pi, it has been my experience that an alternate Raspbian image may not work correctly with the instructions provided on this page. This is not an issue with the instructions, as much as it is that the Raspberry Pi designers are frequently optimizing the design, and this occasionally changes the interactions with the low-level hardware. Most people wouldn't notice these changes, but for a hobbyist trying to use the UART, I2C, SPI, or GPIO interfaces, these changes can be a little frustrating.

Here is a copy of the image that I used while creating these instructions:

• 2017-01-11-raspbian-jessie.zip
• SHA-1: F987935E3E99366A6F1BF0D60A7A83FE3EDB013C (For the zip archive)
• SHA-1: 5903A4A6FAC37F75FA21F616F7506F52E3C19C07 (For the image only)

Notice that both here and on the official Raspbian download page, a checksum is provided. It is highly recommended that you verify the downloaded image to ensure that it is not corrupted before using it. To do this, download and run the MD5-SHA_Checksum Utility. Unselect all of the checkboxes except for SHA-1 (this just speeds things up). Copy the SHA-1 checksum provided with the file, and paste it into the "Hash:" textbox. Click Browse and navigate to the downloaded file. The calculation of the checksum will begin immediately. When the calculation of the checksum is complete, click on the Verify button. If you you get a pop-up window that says "SHA-1 Hash matched.", then life is good.

Next, the image needs to be loaded onto the SD card. To do this, download and run the win32diskimager. Select the blue folder icon to the right side of the Image File textbox to browse for and select the image file to be written. Select the drive letter of the SD card that you want the image written to. IMPORTANT: be very sure that you are selecting the correct drive letter. Once you are absolutely sure, select the Write button. This will begin the writing process. On my computer, writing to an 8GB card takes about 11 minutes.

First-Time Configuration

Place the SD card with the freshly written image into the Raspberry Pi, and apply power. (This assumes that keyboard, mouse, and display are already properly connected) On older images, like Rasbian-Wheezy, the Raspberry Pi Software Configuration Tool (raspi-config) would launch automatically the very first time that power was applied. That isn't true for this Rasbian-Jessie image, however that's probably because it seems like more of the hardware "just works" by default. What you should see on startup, is a nice picture of a highway at sunrise, like this

To start the configuration tool manually, open a terminal window, enter the following, and press enter.

This will open the Raspberry Pi Software Configuration Tool, which should look like this:

Within this window, perform the following actions:

• Select 1 Expand Filesystem
• (a message should indicate success, and that it will occur on next reboot)

• Select 4 Internationalization Options
• Select I1 Change Locale
• Unselect en_GB.UTF-8 UTF-8
• Select en_US.UTF-8 UTF-8
• (spacebar selects/de-selects. Press enter to exit)
• On exit, you may be asked to “Select the default locale for the system environment”. Select en_US.UTF-8

• Select 4 Internationalization Options
• Select I2 Change Timezone
• Select Geographic area = US
• Select Eastern

• Select 4 Internationalization Options
• Select I3 Change Keyboard Layout
• Select Generic 105-key (Intl) PC
• In Keyboard layout select Other
• In Country of Origin... select English (US)
• In Keyboard layout select English (US)
• Key to function as AltGr: Left Logo Key
• Compose key: No compose key
• Use Control+Alt+Backspace to terminate X server?: No

• Select 4 Internationalization Options
• Select I4 Change Wi-Fi country
• Select the country in which the Pi is to be used

• Select 7 Advanced Options
• Select A6 SPI
• Would you like the SPI interface to be enabled? Yes

• Select 7 Advanced Options
• Select A7 I2C
• Would you like the ARM I2C interface to be enabled? Yes

• Select 7 Advanced Options
• Select A8 Serial
• Would you like a login shell to be accessible over serial? No

• Select 7 Advanced Options
• Select AA 1-Wire
• Would you like the one-wire interface to be enabled? Yes

Tab to <Finish> and press Enter. In the window that appears, select <Yes> to answer the question of whether to reboot now, and press Enter.

User documentation for raspi-config can be found at: raspi-config documentation

Enable Low-Level Hardware Control

Next, load some kernel modules to enable the low-level drivers that hobbyists will want for various projects. These are not normally enabled in typical Linux distributions.

Open a terminal window, and enter

Add or ensure the following lines are at the end of the file:

After adding the text, save the file, and exit.

In this image, there are no blacklisted items, so there is no need to remove any items from the blacklist file: /etc/modprobe.d/raspi-blacklist.conf.

Because we selected no to serial over a login shell, there is also no need to remove the "console=serial0,115200" text in the file: /boot/cmdline.txt. However, the serial port will be disabled. To re-enable the serial UART, open a terminal window, and enter

Change the enable_uart setting or ensure the following line is in the file:

If you have a Raspberry Pi 3, there are extra steps required to make the serial port work in this version of Raspbian. When wireless was added to the Raspberry Pi 3 the hardware serial UART was used to communicate with the wireless Bluetooth hardware, and a software UART was put in its place. Unfortunately the software UART is not reliable. I tried streaming data to it at 57600 Baud, and it frequently missed bytes. That's simply not acceptable. It is possible however to disable Bluetooth, and return the hardware serial UART back to user control.

Open a terminal window, and enter

Add the following to the end of the file:

After adding the overlay, and rebooting the Rasbperry Pi, the Bluetooth icon will be greyed out, and if you check the devices using "ls -l /dev" you will see that the serial0 port is now mapped to ttyAMA0, which is the hardware UART.

Update the Linux Image

For the next steps an internet connection is required. If you are connecting with a wired LAN connection, then everything is automatic and you can ignore this section. If you have a wireless connection then there are only a few simple steps to create a connection. Click on the Internet Connection icon on the desktop. If there are wireless connections available they will show up in a selection list. Click on the desired Wireless SSID, and (assuming it is an encrypted connection) a window will pop-up asking for the Pre Shared Key. Enter the key (your WiFi password) and select OK. The connection should be made automatically.

This command downloads the package lists from the repositories and updates them to get information on the newest versions of the packages and their dependencies. It does not change any of the software on the Raspberry Pi. While this is working you should see the http addresses of various repositories, with incrementing progress (to 100%), and finally a message that indicates "Fetched N,NNN kB in XXs (YYY kB/s)", "Reading package lists... Done", and a return to a command prompt. Now enter:

This command will install the newest version of all packages that are currently installed on the Raspberry Pi. This step can take a very long time! So, if you want to go see a movie or take the family out for dinner, now would be a good time, BUT, don't walk away just yet. There is one upgrade (at the time of writing this page) that displays a man page that requires quitting out before upgrading will continue. When this page is displayed, press 'q' to quit, and the upgrade should proceed. Now you can walk away.

After this upgrade, reboot before continuing. You will get a message when it restarts that several of the configuration files have been overwritten. Acknowledge the message, and continue.

Note: After the image upgrade, if you need to run raspi-config again, be aware that the Advanced Options like I2C, SPI, Serial, etc., have moved to a new location under

Install Python Packages

In order to control the hardware peripherals such as GPIO pins, or communications with UART, SPI, I2C, you will need to have some Python libraries installed. Before continuing however, let's start with bringing everything up to date. Open a command-line window, such as LXTerminal, and type the following:

Using the command-line prompt, install the following Python packages, in this order:

For Python development I like to use Geany, and to auto-launch Python scripts, I use xterm. Install these applications by entering the following:

Disable Screen Blanking

As a hobbyist it is very likely that you will want the display to stay on, and not perform the screen blanking of a typical Linux distribution. To make this happen, enter the following:

Add the following lines to the [SeatDefaults] section:

The x11 utils are already loaded in this version of Raspbian. If they weren't you would need to install xset, a lightweight application that controls X settings, by entering the following:

Create a file at ~/.xinitrc by entering the following:

Inside the blank file, enter the following:

Now restart the Raspberry Pi to reload the new settings. Enter the following:

HDMI Display Settings

Normally, the HDMI output is only enabled if a connection is detected at startup. If you are using the Raspberry Pi in a configuration where the display may not be connected at startup, for example where it may run autonomously, but where you may want to be able to later connect an HDMI display to view a running script, or in some cases where the display and Pi are powered on at the same time and proper HDMI negotiation isn't occurring, the following steps can resolve the situation.

Open a terminal window, and enter

Uncomment the following line:

Note: When the HDMI port is forced on (i.e. the monitor was not available to negotiate settings at power-on), the resolution will default to a value which may be lower than the connected display. These settings are not re-negotiated at each connection, only at power-on. If you know the settings for your display, you can force those settings by also adding the following to the /boot/config.txt file.

Add the following line after the hdmi_force_hotplug=1:

The values shown above are for the SunFounder 10.1 inch LCD Display. Replace these values with your own. The format is hdmi_cvt=<width> <height> <framerate> <aspect> <margins> <interlace> <rb>. The <width> is the width in pixels, and <height> is the height in pixels. <framerate> is the frame rate (a.k.a. refresh rate) in Hz. <aspect> is the aspect ratio, which is a pick list value. The options are: 1=4:3, 2=14:9, 3=16:9, 4=5:4, 5=16:10, and 6=15:9. The options for <margins> are 0=margins disabled, or 1=margins enabled. The options for <interlace> are 0=progressive, or 1=interlaced. The options for <rb> are 0=normal, or 1=reduced blanking.

While still in the config.txt file, find the following lines, uncomment them if needed (delete the # mark in font of the line to uncomment it), and change them as shown:

hdmi_group=2 indicates using DMT (Display Monitor Timings), which is the standard typically used by monitors. hdmi_mode=87 indicates using the custom CVT mode that was added above. hdmi_drive=2 selects the Normal HDMI mode.

If you aren't sure what HDMI settings that you want to use, try this trick. First make sure the HDMI lines above are all commented out first. Power down the Raspberry Pi, connect the HDMI display that you want to use to the Raspberry Pi, and then power-up the Raspberry Pi. At start-up the HDMI settings will be negotiated. After start-up, open a terminal window, and enter:

This will provide the current HDMI settings. If these settings look good to you, then add them to the hdmi_cvt command above.

Auto-Starting a Script

For many hobby projects it is desirable to have the Raspberry Pi automatically start doing something when power is applied, without having to interact with it. Perform the following steps in order have the Raspberry Pi auto-execute a bash script on startup.

Open a terminal window, and enter

This will create a new empty file. In that file, enter the following items, save the file, and exit.

In the terminal window, enter the following:

This will return to the /home/pi directory, and create a new empty file. In that file, enter the following items, save the file, and exit.

At this point, this will only open an xterm window at startup. Later, this xterm window will be used to auto-launch the Python script by adding to the end of the xterm line, as an example: -e "sudo python ./datalogger/datalogger.py". The -e command tells the xterm window to execute the text provided in the double-quotes. The sudo is required if the python code is going to be accessing low-level hardware like I2C.

In the terminal window, enter the following to make the startup script executable:

If you list the contents of the directory using ls, the startup.sh script will be highlighted green to show that it is now executable.

Save the "Project-Ready" Image

Now that you have gone through all of the work to make your Raspberry Pi "Project-Ready", it is highly recommended that you use the win32diskimager to save your image. This way, when you start a new project, or make an unrecoverable mistake during a project, you can easily start again from this point. Gracefully power down the Raspberry Pi by either selecting Shutdown from the desktop, or by typing the following in a command-line window:

After the Raspberry Pi powers down, unplug the Raspberry Pi, remove the micro-SD card, place it into an micro-SD card reader, and put the reader into an available USB port on the PC. Open the win32diskimager, select the blue folder icon to the right side of the Image File textbox, and browse to the location where you would like to save the new image. I recommend giving it a name such as "raspbian-jessie-project-ready.img". Select the drive letter of the SD card that you want to read the image from. IMPORTANT: be very sure that you are selecting the correct drive letter. Once you are absolutely sure, select the Read button (NOT the Write button). This will begin reading from the SD card, and writing to the file on the PC. On my computer, reading from an 8GB card takes about 32 minutes.